<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Multi-Instrumentation Manager</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_drmgr.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Multi-Instrumentation Manager </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The <code>drmgr</code> DynamoRIO Extension provides a mediator for combining and coordinating multiple instrumentation passes. It replaces certain DynamoRIO events and API routines with its own versions that mediate among multiple components, typically several libraries and one client, though it is also useful for splitting a client up into modules. <code>drmgr</code> facilitates developing instrumentation frameworks and libraries that can be composed and combined.</p>
<ul>
<li><a class="el" href="page_drmgr.html#sec_drmgr_setup">Setup</a></li>
<li><a class="el" href="page_drmgr.html#sec_drmgr_events">Event Replacement</a></li>
<li><a class="el" href="page_drmgr.html#sec_drmgr_stages">Instrumentation Stages</a></li>
<li><a class="el" href="page_drmgr.html#sec_drmgr_tls">Thread-Local and Callback-Local Storage</a></li>
<li><a class="el" href="page_drmgr.html#sec_drmgr_notes">Instruction Note Fields</a></li>
</ul>
<h1><a class="anchor" id="sec_drmgr_setup"></a>
Setup</h1>
<p>To use <code>drmgr</code> with your client simply include this line in your client's <code>CMakeLists.txt</code> file:</p>
<div class="fragment"><div class="line"> use_DynamoRIO_extension(clientname drmgr) </div>
</div><!-- fragment --><p>That will automatically set up the include path and library dependence.</p>
<p>The <code><a class="el" href="group__drmgr.html#ga07ab03a2182247922f756778d18bb3fd">drmgr_init()</a></code> function may be called multiple times; subsequent calls will be nops and will return <code>true</code> for success. This allows a library to use <code>drmgr</code> without coordinating with the client over who invokes <code><a class="el" href="group__drmgr.html#ga07ab03a2182247922f756778d18bb3fd">drmgr_init()</a></code>.</p>
<h1><a class="anchor" id="sec_drmgr_events"></a>
Event Replacement</h1>
<p>In order to provide ordering control over event callbacks, <code>drmgr</code> replaces a number of DynamoRIO's events. For many of these, simply replacing <code>dr_</code> with <code>drmgr_</code> is sufficient, as that will then use a default priority. To request a priority, use the <code><em>ex</code> version of the <code>drmgr_register</em></code> routine. The basic block event is a special case as it is completely replaced with a new set of multiple events for different stages of instrumentation.</p>
<h1><a class="anchor" id="sec_drmgr_stages"></a>
Instrumentation Stages</h1>
<p><code>drmgr</code> divides code changes into three types:</p>
<ol type="1">
<li>Application-to-application transformations: changes to the application code itself that are meant to affect application behavior or application performance</li>
<li>Instrumentation insertion: monitoring code added between the application instructions</li>
<li>Instrumentation-to-instrumentation transformations: typically, optimizations applied to the full set of inserted instrumentation</li>
</ol>
<p>Instrumentation insertion is split into two pieces: analysis of the full application code (after any changes from its original form), followed by insertion of instrumentation, one instruction at a time. The result is four separate, sequential stages:</p>
<ol type="1">
<li>Application-to-application transformations</li>
<li>Application code analysis</li>
<li>Instrumentation insertion, one instruction at a time</li>
<li>Instrumentation-to-instrumentation transformations</li>
</ol>
<p>Each component that registers with <code>drmgr</code> can register for some or all of the four stages. In each stage, each registered compoment's callback is invoked. This groups the different types of changes together and allows them to assume that no later change will invalidate their analysis or actions. The instrumentation insertion is performed in one forward pass: for each instruction, each registered component is invoked. This simplifies register allocation (register allocation is provided by a separate Extension <code>drreg</code>).</p>
<h2><a class="anchor" id="sec_drmgr_ordering"></a>
Ordering</h2>
<p>The proper ordering of instrumentation passes depends on the particulars of what each pass is doing. <code>drmgr</code> supports naming each pass and specifying relative ordering by requesting that one pass occur before and/or after another named pass. Numeric priorities are also supported for resolving order among identical placement once named ordering is resolved.</p>
<p>Some ordering rules do apply. For example, function replacing should occur before most other application transformations. Ordering of instrumentation insertion and especially instrumentation-to-instrumentation transformations can be highly dependent on exact transformations involved. Care should be taken when ordering passes within each stage.</p>
<h2><a class="anchor" id="sec_drmgr_traces"></a>
Traces</h2>
<p><code>drmgr</code> does not mediate trace instrumentation. Those interested in hot code should use the <code>drmgr</code> basic block events and act only when the <code>for_trace</code> parameter is set. Those wanting to optimize the longer code sequences in traces are on their own for register allocation, and must be careful to handle instrumentation that has already been added from the basic block events.</p>
<h1><a class="anchor" id="sec_drmgr_tls"></a>
Thread-Local and Callback-Local Storage</h1>
<p><code>drmgr</code> also coordinates sharing of the thread-local-storage field among multiple components and provides automated support for callback-private fields on Windows. It replaces the single <a class="el" href="dr__tools_8h.html#a787aff5df1ded3de8a7ce9f3efef0594">dr_get_tls_field()</a> pointer with two separate arrays of pointers: one for callback-shared fields, and one for callback-private fields. When a field is requested, an integer index is returned to the caller for use in retrieving the appropriate pointer.</p>
<h2><a class="anchor" id="sec_drmgr_cls"></a>
Callback-local Storage</h2>
<p>On Windows, events such as keypresses or mouse movements are delivered to applications as <em>callbacks</em>. These callbacks interrupt a thread's execution in order to handle the event. The interrupted context is saved and a new context entered. When the event handling is finished, the interrupted context is resumed. Callbacks can interrupt other callbacks, resulting in a stack of contexts.</p>
<p>When a tool maintains state across application execution, it must handle callback contexts. Thread-local storage (tls) is per-thread and is thus callback-shared. Callbacks interrupt thread execution to execute arbitrary amounts of code in a new context before returning to the interrupted context. Thread-local storage fields that persist across application execution can be overwritten during callback execution, resulting in incorrect values when returning to the original context. Callback-local storage, rather than thread-local storage, should be used for any fields that store information specific to the application's execution.</p>
<p>Callbacks are Windows-specific. The cls interfaces are not marked for Windows-only, however, to facilitate cross-platform code. We recommend that cross-plaform code be written using cls fields on both platforms; the fields on Linux will never be stacked and will function as tls fields. Technically the same context interruption can occur with a Linux signal, but Linux signals typically execute small amounts of code and avoid making stateful changes; furthermore, there is no guaranteed end point to a signal. The <a class="el" href="group__drmgr.html#gae2a70abba090ee410babc6a1548bb21d">drmgr_push_cls()</a> and <a class="el" href="group__drmgr.html#ga4ac55faa0a4274ab5d8ac1cbd247b569">drmgr_pop_cls()</a> interface can be used to provide a stack of contexts on Linux, or to provide a stack of contexts for any other purpose such as layered wrapped functions. These push and pop functions are automatically called on Windows callback entry and exit.</p>
<h1><a class="anchor" id="sec_drmgr_notes"></a>
Instruction Note Fields</h1>
<p>Instrumentation passes often need to mark instructions with information for later passes. One method of doing this is to use the <code>note</code> field built in to the <code><a class="el" href="structinstr__t.html">instr_t</a></code> type. For example, labels can be inserted with their <code>note</code> fields corresponding to pre-defined constants to indicate insertion points. In order to avoid these <code>note</code> constants from overlapping and conflicting among different components or passes, <code>drmgr</code> provides mediation of the namespace.</p>
<p><code>drmgr</code> does not make use of its <code>note</code> mediation mandatory and does not override <a class="el" href="dr__ir__instr_8h.html#a85a8f92faa0d368fec240e6fa819ca9c">instr_set_note()</a> or <a class="el" href="dr__ir__instr_8h.html#a776a1fd0cf8f783b2a969a24432fee6e">instr_get_note()</a>. Instrumentation passes should feel free to use pointer values in the <code>note</code> field. The <code>note</code> constant value mediation is intended for small constants that will not be confused with pointer values. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
